Copyright: ® 1995-97 Reinhard Kalinke EDV Beratung


PicEdits Unit
PicEdits Units

The following items are declared in the PicEdits units:

Components

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

TPxValcheckRetriever

Types

EPxValidateError

Installation

Installation hints

Tips&Tricks

Date & Time issues

Tips for handling validation on a form

Tips on Errors with TDBPxPicEdit/Grid

Tips for using PicEdits with different kinds of databases

The Picture mask syntax

One of the (few) shortcomings of Delphi is the implemantation of EditMasks: the masks you
can define aren't too flexible and with DBEdit controls it's a shame that the valchecks of
Paradox tables aren't supported. So I tried to write a set of Edit controls that deal with
these shortcomings.

Over the time PicEdits became a tool to handle almost any kind of validity check with almaost any kind of database that uses the BDE. They even works with C/S if you want them to.

This finally is version 1.7 of PicEdits. I'd like to thank all beta testers and bug-finders for
their help and patience. Without you it wouldn't have been possible.

Please keep on informing me of any bugs, flaws or shortcomings you encounter so that this
list can be completed. Please send reports and comments to Reinhard Kalinke (100417,
3504 @compuserve.com).

If you are interested in Paradox table valchecks, don't miss the file PXVALTBL.ZIP in CIS
Delphi, lib 6 (Database). It's a descendant of TTable and does retrieving and setting of
Paradox valchecks!

This trial version displays an info with each message you define and a message dialog for every instance of PicEdits on app start-up outside Delphi. Apart from this, they run in- and outside the Delphi environment without further restrictions. Source is available now, too. See 'How To Register' for details.

Be sure to read the TIPS section!

Disclaimer


TDBPxPicEdit Component

Properties	Methods	Events

Unit

PxDBEdit

see also

TPxValcheckRetriever

Description

NOTE
The 32bit D2 version of TDBPxPicEdit is 'replicable' so that it can be used with TDBCtrlGrid.

DBPxPicEdit automatically retrieves the valcheck picture, min, max and default values
and the required-status of the connected field from a Paradox table's val file. If you want
to set table valchecks from within your app, have a look at PXVALTBL.ZIP in CIS Delphi,
lib 6 (Database).

If you want to make use of DBPxPicEdit with other db's than Paradox, or want to have
some more control over the valchecks retrieved, you have to use a TPxValcheckRetriever
component.

DBPxPicEdit is derived from TCustomEdit (not TCustomMaskEdit), so the validation of any
EditMask supplied with the connected TField doesn't take place (you can, however, use a
TField's EditMask to format the text display of DBPxPicEdit). Any user input is immediately
validated with the valcheck picture. DBPxPicEdit also supports the AutoFill capabilities of a
Paradox picture. Please refer to the DBD online help for an explanation of the Paradox
valcheck picture syntax.

As long as in edit mode, on attempting to leave the edit control a complete validation will be
done (even if this particular field has not been changed): if the text is an empty string, the
default value will be supplied, the text is then checked for required, completeness of picture,
min and max values in that order. To have validation performed on all DBPxPicEdits
regardless of having 'visited' them have a look at the tips sections.

Last version was introducing another component, TPxValcheckRetriever. You can place one
instance of this component on your form and connect all DBPxPicEdit controls to it via the
VchkRetriever property. To save your former setup, DBPxPicEdit still does retrieving on it's
own, without using a PxValcheckRetriever, as long as you include PXVALRTR.DCU in your
complib's search path. If you want to make use of custom valchecks be sure to install
TPxValcheckRetriever to your complib as well.

TDBPxPicEdit now supports a 'Special Autodetecting Abbreviation Mode'.<g> Supposed you
have an A1 field with a picture 'Left,Right,Top,Bottom', TDBPxPicEdit will show the picture
instead of the value for edit and display. If TDBPxPicEdit's text length is > fieldsize, the
backspace and del will cut the text at pos fieldsize-1 (in the above example: clear the text.
Else this is the maximum text length supposed to still be ambiguous, that is leaving sth to be edited.)

All properties, methods and events not mentioned here are the same as with the regular
T(DB)Edit apart from the EditMask property of TDBPxPicEdit, which is not available.
The Grid will also ignore any EditMask settings of the underlying TFields. After all, you
have the pictures...


Properties

DefaultMode	ErrMessPicPaste	PxPicture

DefaultValue	ErrMessRequired	PxRequired

ErrMessBeep	MaxValue	Required

ErrMessHandling	MinValue	VchkRetriever

ErrMessMax	Picture	Version

ErrMessMin	PxDefaultValue	PicInsertCheck

ErrMessPicExit	PxMaxValue	PicInsertCheck

ErrMessPicInput	PxMinValue


DefaultMode Property

Applies To

TDBPxPicEdit

TDBPxPicGrid

Declaration

property DefaultMode: TPxDefaultMode;

Description

(not used yet)


Databases
Using PicEdits with different kinds of databases

see also

TPxValcheckRetriever

The key to using PicEdits with different kinds of databases is the TPxValcheckRetriever component. The main purpose of this component is providing a central place in your app to set or retrieve valchecks.

- you can store valchecks for your table(s) in an ini file. Default extension is VCH so that the end user does not recognize it right away. You can determine the directory this file will be looked for so that you can use it with SQL databases as well. Last not least you can determine whether each table has it's own file or if your tables share a single VCH file.

- you can use the OnAfterRetrieve event of TPxValcheckRetriever to supply values at runtime or to write your own method of storing, using this event to pass the values to your PicEdit components.

For a more detailed discussion of these possibilities have a look at the TPxValCheckRetriever properties, methods and events and have a look at the PXDEMO sample app.


DefaultValue Property

Applies To

TDBPxPicEdit

Declaration

Px*Value: TCaption;

Description

PxMinValue, PxMaxValue, PxDefValue and PxPicture (Strings); PxRequired (Boolean):

At runtime, you can use these properties to read the retrieved valchecks of the connected
field. For setting valchecks for Paradox tables please have a look at file PXVALTBL.ZIP, CIS
Delphi, lib 6, Database.


DrawPicture
DrawPicture property

Applies to

TDBPxPicGrid

Declaration

DrawPicture: boolean;

Description

When set to True TDBPxPicGrid will 'expand' the text of any field that has a picture
setting. For instance if you have a A1 or C1 field with a picture of Left,Right, the grid will
display 'Left' and 'Right' instead of 'L' or 'R'.

Set DrawPicture to False if you want to speed up the drawing of TDBPxPicGrid.


ErrMessBeep Property

Applies To

TDBPxPicEdit

Declaration

ErrMessBeep

Description

ErrMessBeep


AutoFill
AutoFill property

Applies to

TDBPxPicGrid

see

AutoFill


ErrMessMax Property

Applies To

TDBPxPicEdit

Declaration

ErrMessMax

Description

ErrMessMax


FixedCols Property

Applies to

TDBPxPicGrid

See also

FixedColor

Declaration

FixedCols: Integer;

Description

Fixes left hand columns in the grid. These columns are not scrolled when moving in the grid
and can not be entered or edited.


ErrMessMin Property

Applies To

TDBPxPicEdit

Declaration

ErrMessMin

Description

ErrMessMin


TitleColor Property

Applies to

DBPxPicGrid

See also

FixedColor

Declaration

TitleColor: TColor;

Description

Determines the color of the title bar (where the field names are displayed).


ErrMessPicExit Property

Applies To

TDBPxPicEdit

Declaration

ErrMessPicExit

Description

ErrMessPicExit


TPxValcheckRetriever Tasks

If you want to use PicEdits solely with Paradox tables and *.val valchecks you _won't_ need
TPxValcheckRetriever. DBPxPicEdit/Grid can do *.val retrieving on their own (by creating an
internal retriever). The retriever comes in when it comes to custom valchecks and storing custom
valchecks in ini files - i.e. when it comes to non-Paradox tables. The retriever has three sources of
valchecks:

1) the Paradox *.val file
2) a custom valcheck ini file
3) the AfterRetrieve event

Sources 2 and 3 can of course be used with Paradox as well but are meant to support non-Paradox tables in the first place. Option 2 will write and retrieve valchecks to/from an ini file that is stored either with the table (e.g. MYTABLE.VCH for table MYTABLE.DBF - just like the *.val with *.db Paradox tables) or - when a name/directory for that ini file is specified - in a single ini file holding the valchecks for a number of tables (both options having their pros and cons).

If you want to implement his own way of storing or setting valchecks, you can use the
retriever's AfterRetrieve event. You can set them in code or write your own storing procedure.

The idea behind this hassle is to provide a 'central place' for setting valchecks. When a field
shows up more than once in an app you don't need to synchronize their edit's valchecks in code
but you connect them to a retriever that either uses custom ini files or a common AfterRetrieve
handler.

There are reports that PicEdits are used successfully with dBase, dBase/Apollo and SQL databases like InterBase and MS SQL...


ErrMessPicInput Property

Applies To

TDBPxPicEdit

Declaration

ErrMessPicInput

Description

ErrMessPicInput


FixedColsFontColor Property

Applies to

TDBPxPicGrid

See also

FixedCols

Declaration

FixedColsFontColor: TPxFixedColsFontColor;

Description

Determines whether the color of TitleFont or the color of Font is used to display text in fixed cols.

Possible values are  ffcFontColor and ffcTitleFontColor.


ErrMessPicPaste Property

Applies To

TDBPxPicEdit

Declaration

ErrMessPicPaste

Description

ErrMessPicPaste


IndicatorBkColor Property

Applies to

TDBPxPicGrid

Declaration

IndicatorBkColor: TPxIndicatorBkColor;

Description

Determines whether TitleColor or FixedColor is used as the background
color of the indicator column.

Possible values are ibkTitleColor and ibkFixedColor.


ErrMessRequired Property

Example

Applies To

TDBPxPicEdit

Declaration

ErrMessRequired

Description

ErrMessRequired


Picture mask syntax
The Picture mask syntax

Picture masks were originally introduced by Borland for the use with Paradox tables. Here's a list of the special characters and their meaning:

#	any number [0..9]
@	any character
!	any character (letters will be converted to uppercase)
?	any letter
&	any letter (will be converted to uppercase)
;	the following sign will be interpreted as a literal, not a special char
*	repeats the following character (if followed by a number this number of repetions will be
enforced, otherwise any number is allowed)
[]	embraces optional elements
{}	grouping operator
, 	separator

Any mask containing literals will be automatically completed when the typed-in entry becomes inambigious.

Some examples:

mask	verbose	samples of entries allowed

#*#	any 'integer' value with at least one digit	1 / 784 / 1234567
#,##	one digit, two decimals	1,23 / 7,45 / 9,23
#&#&#&	Canadian zip code	1A2B3C / 5F7H4D
*!	any entry, letters uppercase	JJU / 345 / K1L
{True,False}	either 'True' or 'False'	True / False
{Red,B{lue,rown}}  either 'Red', 'Brown' or 'Blue'	Red / Brown / Blue

NOTE on the last example: due to the automatic completion you must set up pictures like that very carefully. Suppose you're using this instead:

{Red,Blue,Brown}

in this case the user will not be able to enter 'Brown' because as soon as 'B' is entered the entry will become 'Blue'!

You might find some more info the syntax in DBD help or even better in any Paradox manuals / help files you might own. You can also use DBD or Paradox to play around with some more sample masks. Just create a simple Paradox table holding an Aplha field and the chose 'Picture masks' from the 'Validity checks' list in the create/restructure dialog.

If you need help to set up a specific mask don't hesitate to drop me a mail.


MaxValue Property

Applies To

TDBPxPicEdit

Declaration

MaxValue

Description

MaxValue


Scrollbars property

Applies to

TDBPxPicGrid

Declaration

property Scrollbars: TScrollType;

Description

In case you don't want the grid to display a horizontal scrollbar (for example in a one-field grid) you can use this runtime-only property to suppress the horizontal scrollbar. Insert a line

MyDBPxPicGrid.Scrollbars := ssNone;

at a proper place like Form.OnCreate for example. The display of the vertical scrollbar is not affected by this property.


MinValue Property

Applies To

TDBPxPicEdit

Declaration

MinValue

Description

MinValue


PicInsertChange property
PicInsertCheck property

Applies to

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

property PicInsertCheck: boolean;

Description

This property determines whether the input is validated against a picture mask when the user inserts characters into the edit text. Set this property to False if you want to allow your users to select more than one character 'inside' the edit text and delete and/or replace them without being prompted for invalid input. When False the input is still validated when the caret is at the end of the text. It is also validated as usual when the user tries to exit the edit control.


Picture Property

Applies To

TDBPxPicEdit

Declaration

Picture

Description

Picture


Picture Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Required Property

Applies To

TDBPxPicEdit

Declaration

Required

Description

Required


Required Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


VchkRetriever Property

Applies To

TDBPxPicEdit

TDBPxPicGrid

Declaration

property VchkRetriever: TPxValcheckRetriever;

see also

TPxValcheckRetriever

Description

TPxValcheckRetriever is an optional component in so far as DBPxPicEdit and DBPxPicGrid can retrieve Paradox valchecks on their own. However, for using custom valchecks or common errormessages you have to employ a separate ValcheckRetriever and connect it to the Edits and Grids via this property. You can have more than one instance on a form to deal with permanently changing setups.


VchkRetriever Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Version Property

Applies To

TDBPxPicEdit

Declaration

Version

Description

Version


Version Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Methods

IsValidPicInput	PicValidate	IsValidPicValue

Validate


IsValidPicInput Method

Applies To

TDBPxPicEdit

Declaration

function IsValidPicInput(VText: string): Boolean; virtual;

Description

IsValidPicInput


IsValidPicValue Method

Applies To

TDBPxPicEdit

Declaration

function IsValidPicValue(VText: string): Boolean; virtual;

Description

IsValidPicValue


PicValidate: Method

Applies To

TDBPxPicEdit

Declaration

function PicValidate: Boolean; virtual;

Description

PicValidate


Validate: Method

Applies To

TDBPxPicEdit

Declaration

function Validate: Boolean; virtual;

Description

Validate


Events

OnFailValidate	OnValidate


OnFailValidate Event

Applies To

TDBPxPicEdit

Declaration

OnFailValidate

Description

OnFailValidate


OnValidate Event

Applies To

TDBPxPicEdit

Declaration

OnValidate

Description

OnValidate


TDBPxPicGrid Component

Properties	Events

Unit

PxDBGrid

see also

TPxValcheckRetriever

Description

NOTE
The 32bit TDBPxPicGrid is a descendant of the 'old' D1 16bit grid. It does not offer the new
D2/D3 features like the Columns property etc.

DBPxPicGrid automatically retrieves the valcheck picture, min, max and default values and
the required-status of the connected field from a Paradox table's val file. If you want to set
table valchecks from within your app, have a look at PXVALTBL.ZIP in CIS Delphi, lib 6
(Database).

If you want to make use of DBPxPicGrid with other db's than Paradox, or want to have
some more control over the valchecks retrieved, you have to use a TPxValcheckRetriever
component.

The editor within DBPxPicGrid is derived from TCustomEdit (not TCustomMaskEdit), so the
validation of any EditMask supplied with the connected TField doesn't take place (you can,
however, use a TField's EditMask to format the text display). Any user input is immediately
validated with the valcheck picture.

As long as in edit mode, on attempting to leave the edit control a complete validation will
be done (even if this particular field has not been changed): if the text is an empty string,
the default value will be supplied, the text is then checked for required, completeness of
picture, min and max values in that order.

You can place a TPxValcheckRetriever on your form and connect all DBPxPicGrid controls
to it via the VchkRetriever property. If you want to make use of custom valchecks you have
to employ a TPxValcheckRetriever.

All properties, methods and events not mentioned here are the same as with the regular
(16bit) TDBGrid. The Grid will also ignore any EditMask settings of the underlying TFields.
After all, you have the pictures...


Properties

AutoFill	ErrMessPicInput	Scrollbars

DefaultMode	ErrMessPicPaste	TitleColor

DrawPicture	ErrMessRequired	VchkRetriever

ErrMessBeep	FixedColor	Version

ErrMessHandling	FixedCols	Scrollbars

ErrMessMax	FixedColsFontColor	PicInsertCheck

ErrMessMin	IndicatorBkColor	PicInsertCheck

ErrMessPicExit	IndicatorColor


DefaultMode Property

Example

Applies To

TDBPxPicGrid

Declaration

property DefaultMode: TPxDefaultMode;

Description

DefaultMode


DefaultMode Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessBeep Property

Applies To

TDBPxPicGrid

Declaration

ErrMessBeep

Description

ErrMessBeep


ErrMessBeep Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessMax Property

Applies To

TDBPxPicGrid

Declaration

ErrMessMax

Description

ErrMessMax


ErrMessMax Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessMin Property

Applies To

TDBPxPicGrid

Declaration

ErrMessMin

Description

ErrMessMin


ErrMessMin Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicExit Property

Applies To

TDBPxPicGrid

Declaration

ErrMessPicExit

Description

ErrMessPicExit


ErrMessPicExit Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicInput Property

Applies To

TDBPxPicGrid

Declaration

ErrMessPicInput

Description

ErrMessPicInput


ErrMessPicInput Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicPaste Property

Applies To

TDBPxPicGrid

Declaration

ErrMessPicPaste

Description

ErrMessPicPaste


ErrMessPicPaste Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessRequired Property

Applies To

TDBPxPicGrid

Declaration

ErrMessRequired

Description

ErrMessRequired


ErrMessRequired Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


VchkRetriever Property

Applies To

TDBPxPicGrid

Declaration

property VchkRetriever: TPxValcheckRetriever;

Description

VchkRetriever


VchkRetriever Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Version Property

Applies To

TDBPxPicGrid

Declaration

Version

Description

Version


Version Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Events

OnFailValidate	OnValidate


OnFailValidate Event

Applies To

TDBPxPicGrid

Declaration

OnFailValidate

Description

OnFailValidate


OnValidate Event

Applies To

TDBPxPicGrid

Declaration

OnValidate

Description

OnValidate


TPxPicEdit Component

Properties	Methods	Events

Unit

PxEdit

Description

PxPicEdit is meant to be an alternative to the TMaskEdit supplied with Delphi. It uses a
Paradox-style picture instead of a Delphi mask. Any user input is validated against this
picture as soon as a value is entered. AutoFill capabilities are supported, too. Furthermore
you can use the Alignment-property to determine right- left- or center justification of it's
display. For an explanation of the Paradox picture syntax please refer to the DBD online
help.

PxPicEdit also supports min and max validation and default values. You can even use
TODAY- and NOW-calculations with date resp. time edits - that's more than the original
Paradox valchecks can do (details in section 'DefaultValue').

All properties, methods and events not mentioned here are the same as with the regular
T(DB)Edit apart from the EditMask property of TDBPxPicEdit, which is not available.
The Grid will also ignore any EditMask settings of the underlying TFields. After all, you
have the pictures...


Properties

Alignment	ErrMessPicExit	PicInsertCheck

AutoFill	ErrMessPicInput	Required

DefaultValue	ErrMessPicPaste	VchkSubType

ErrMessBeep	ErrMessRequired	VchkType

ErrMessHandling	MaxValue	Version

ErrMessMax	MinValue	ErrMessMin

Picture


Alignment Property

Applies To

TPxPicEdit

Declaration

Property Alignment: TAlignment;

Description

Determines the justification of text display when not focused. For DBPxPicEdit use the
TFields Alignment property to adjust text display.


Alignment Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


AutoFill Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

Property AutoFill: Boolean;

Description

Determines whether a user input is completed when it is unambiguous with one of the
possible values. For example, with AutoFill = True, if the picture is Yes,No the input is
completed to 'Yes' as soon as the user types in 'y' or 'Y'.


AutoFill Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


DefaultValue Property

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

DefaultValue: TCaption;

Description

The DefaultValue is entered when the user leaves the edit control with a blank value.

With vchkDate (see VchkType) you can use %TODAY% (uppercase required) to supply the
current date. You can do calculations with %TODAY% by adding or subtracting an integer
value (=days). Entering '%TODAY%-7' means current date minus 7 days as DefaultValue.

With vchkTime you can use %NOW% (uppercase required) to supply the current time. You
can do calculations with %NOW% by adding or subtracting an integer value (=hours).
Entering '%NOW%-7' means current time minus 7 hours as DefaultValue. You can use
minute values by separating them with ':' from the hour value. '%NOW%-4:30' will subtract 4
hours and 30 minutes from the current time.

With TDBPxPicEdit setting this property will override an retrieved value. Blanking it out again will 'reinstall' the retrieved value. This is useful if you want to alter this value only for a specific edit situation without affecting the 'general' settings for the field in question.


DefaultValue Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessBeep Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessBeep: boolean;

Description

Set this to false if you don't want the control to beep on an error.


ErrMessBeep Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessHandling Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

See also

TPxValcheckRetriever ErrMessHandling

Declaration

ErrMessHandling: TPxErrMessHandling;

Description

TErrMessHandling = (emNoShow, emDialog, emException, emRetriever);

emNoShow: 	No error message will be shown.

emDialog: 	A standard MessageDialog is used to display the error message.

emException:	An exception EPxValidateError, carrying the message, will raised.
For example you can use this to direct the messages to a status panel.

em Retriever:	The controls will retrieve the error messages and the actual
          	ErrMessHandling from TPxValcheckRetriever.

However, with emRetriever 'local' errormessages will not be overriden, allowing you to store
any default messages with the Retriever and still have a custom errormessage with the
controls itself.

NOTE
emRetriever is only valid with the bound components. For backward compatability it's listed
with TPxPicEdit as well, however it can't be selected. (I didn't want to invalidate your 'old'
project files once more)


ErrMessHandling Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessMax Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessMax: TCaption;

Description

Message to be displayed when maximum validation fails.

You can use the placeholder %MAXVAL% (uppercase required) to display the current
MaxValue. For example the message string 'Maximum value is %MAXVAL%!' will
display 'Maximum value is 01/01/97' if it's a date field, the maximum value is
set to %TODAY% and the error is triggered on 01/01/97...


ErrMessMax Example

better dada than gaga

procedure TForm1.Button1Click(Sender: TObject);


ErrMessMin Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessMin: TCaption;

Description

Message to be displayed when minimum validation fails.

You can use the placeholder %MINVAL% (uppercase required) to display the current
MinValue. For example the message string 'Maximum value is %MINVAL%!' will
display 'Minimum value is 01/01/97' if it's a date field, the minimum value is
set to TODAY and the error is triggered on 01/01/97...


ErrMessMin Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicExit Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessPicExit: TCaption;

Description

This message is displayed when the user tries to leave the edit control with an incomplete
value in it. It is also triggered when the user tries to post an incomplete value.


ErrMessPicExit Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicInput Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessPicInput: TCaption;

Description

This message is displayed when the user types in any key that is not allowed with the
picture. This will be left blank in most cases for it is annoying to have to 'ok-away' a message
each time a wrong key is entered.


ErrMessPicInput Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicPaste Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessPicPaste: TCaption;

Description

This message is displayed when the user pastes in a value that is not allowed with the
picture. You should display a message in this occasion for the pasted value is shown for a
short time (didn't yet manage to avoid that) and it simply looks better to have a message
displayed while the incorrect value is shown and have the previous value restored when the
message is removed.


ErrMessPicPaste Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessRequired Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

ErrMessRequired: TCaption;

Description

This message is displayed when the user tries to post or to leave the control with an empty
value and the field is marked 'required'.


ErrMessRequired Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


MaxValue Property

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

MaxValue: TCaption;

Description

The maximum value against which the text is to be validated. This has to be a valid string
according to the VchkType setting. You can use %TODAY%- and %NOW%-calculations with
vchkDate resp. vchkTime as described for DefaultValue.

With TDBPxPicEdit setting this property will override an retrieved value. Blanking it out again will 'reinstall' the retrieved value. Use this if you want to alter this value only for a specific edit situation without affecting the 'general' settings for the field.


MaxValue Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


MinValue Property

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

MinValue: TCaption;

Description

The minimum value against which the text is to be validated. This has to be a valid
string according to the VchkType setting. You can use %TODAY%- and %NOW%-
calculations with vchkDate resp. vchkTime as described for DefaultValue.

With TDBPxPicEdit setting this property will override an retrieved value. Blanking it out again will 'reinstall' the retrieved value. Use this if you want to alter this value only for a specific edit situation without affecting the 'general' settings for the field.


MinValue Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Picture Property

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

Picture: TCaption;

Description

The Paradox-style picture is supplied here. Tip: you can use a (dummy) Paradox table within
the DBD to refine your picture and and have some syntax checking and test entry performed.

With TDBPxPicEdit setting this property will override an retrieved value. Blanking it out again will 'reinstall' the retrieved value. Use this if you want to alter this value only for a specific edit situation without affecting the 'general' settings for the field.


Picture Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Required Property

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

Required: boolean;

Description

Determines whether the edit control can be left with a blank value.

With TDBPxPicEdit setting this property to True will override an retrieved value. Setting it back to False will 'reinstall' the retrieved value. Use this if you want to alter this value only for a specific edit situation without affecting the 'general' settings for the field.


Required Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


VchkSubType Property

Applies To

TPxPicEdit

Declaration

Property VchkSubType: TPxVchkSubType;

Description

(not used yet)


VchkSubType Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


VchkType Property

Applies To

TPxPicEdit

Declaration

VchkType: TPxVchkType;

see also

TPxVchkType;

Description

Determines

a) the datatype of the value accepted by this field. If you have your VchkType set to
vchkDate for example, only valid dates will be accepted regardless of whether any min or
max values are validated.

b) the way the MinMaxValidator works. When you change this setting, Min-, Max- and
DefaultValue are checked for compatability with the new setting. In design mode you will get
an error message for every imcompatible value and the value will be cleared. During runtime,
all values will be cleared when you change this setting. So if you want to change this
property at runtime, be sure to change this first and then supply new values.

There's one exception to this rule: if you change to vchkNone, no values will be cleared (and
no Min/Max validation will be performed regardless of Min- or MaxValues). If you change
back from vchkNone to any other setting, PxPicEdit will try to keep your values. However, if
validation of either Min, Max or Default values fails, the offending value will be cleared.

In design mode, on setting VchkType to vchkDate or vchkTime there will be a picture
suggestion, which should reflect your ShortDateFormat resp. LongTimeFormat settings.

With vchkNumeric, if you want fixed decimals (or no decimals, i.e. integers) you can easily do
this by setting up pictures. Example: #*#[,##] will allow 1 to any number of digits, followed
by either none or  2 decimals. #[#],### will allow 1 or two digits and enforce 3 decimals.
'#*#' is the integer setting.


VchkType Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Version Property

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

TPxValcheckRetriever

Declaration

Version: string;

Description

A published readonly property to indicate the version # you're working with.


Version Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Methods

IsValidPicInput	PicValidate	IsValidPicValue

Validate


IsValidPicInput Method

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

function IsValidPicInput(VText: string): Boolean; virtual;

Description

You can use this method to validate a string with the (DB)PxPicEdit picture before assigning
it at runtime. It returns true if the string is a valid input, it doesn't have to be a complete valid
entry. After assigning a valid input to DBPxPicEdit's Text property, you should set focus to
DBPxPicEdit to have the user complete the entry.


IsValidPicValue Method

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

function IsValidPicValue(VText: string): Boolean; virtual;

Description

This method returns true if the given string is a complete valid entry.


PicValidate: Method

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

function PicValidate: Boolean; virtual;

Description

Call this method to enforce picture validation after assigning a value at runtime.


Validate: Method

Applies To

TPxPicEdit

TDBPxPicEdit

Declaration

function Validate: Boolean; virtual;

Description

Call this method to enforce complete validation of (DB)PxPicEdit's input (for example after
assigning a value at runtime or after having canceled an error in OnFailValidate and having
returned to the edit control. Validation is the same that occurs when the user tries to leave
the control or post the record.


Events

OnFailValidate	OnValidate


OnFailValidate Event

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

OnFailValidate: TPxFailValidateEvent;

see also

TPxFailValidateEvent;

Description

This event is triggered each time a validation fails. It does not cover the exceptions raised by
the BDE when you try to post an illegal value. You can use this event to roll your own error
handling, error dialogs, to direct the error messages to a status panel etc

You can also use this event to override any errors. See TPxFailValidateEvent for details.


OnValidate Event

Applies To

TPxPicEdit

TDBPxPicEdit

TDBPxPicGrid

Declaration

OnValidate: TPxValidateEvent;

see also

TPxValidateEvent;

Description

This event is triggered after validation and before an OnFailValidate event. If you want to do
some additional validation, use this event. FailType is the control's opinion on the validity of
the current text, ErrorMessage is the message it is going to display (if there is any error, that
is). By altering the values of ErrorMessage and FailType you can override the validation
results of the control. Use ValType to determine the kind of validation that's taking place.


TPxValcheckRetriever Component

Properties	Methods	Events	Tasks

Unit

PxValRtr

Description

TPxValcheckRetriever does retrieving of Paradox *.val file valchecks as well as retrieving
and setting custom valchecks at runtime. In order to use the benefits of this component,
place an instance on your form and connect it to the VchkRetriever properties of your
DBPxPicEdits and DBPxPicGrids.

TPxValcheckRetriever will give you full control on the valchecks used by DBPxPicEdit and
DBPxPicGrid. There are four retrieve modes available: PxValOnly and CustomOnly will
retrieve either Paradox *.val file settings or your custom settings. With PxValFirst and
CustomFirst you can determine which settings are dominant if you retrieve both the val file
and the custom settings.

There are two events with TPxValcheckRetriever: OnBeforeRetrieve provides the opportunity
to redirect the valcheck request to another dataset and/or another field and to temporarily
change the retrieve mode. This is extremely useful if you want to edit a live query which will
have neither a val file nor custom settings (as it is being created at runtime...). Simply
evaluate the dataset and field in OnBeforeRetrieve and if it's a query or a temporary table
you supply a table with the original val settings for that dataset.

OnAfterRetrieve presents you with the settings that have been retrieved for the given field
and dataset, providing the opportunity to change each single value.

Finally, the SetCustomValchecks method allows you to set custom valchecks for any table of
your app. The settings are written to a simple ini-file type with the name of your table and
extension *.VCH (no encryption so far). Be sure to distribute those files with you app!


Properties

ErrMessHandling	ErrMessPicInput	IniFileExt

ErrMessMax	ErrMessPicPaste	IniFileName

ErrMessMin	ErrMessRequired	RetrieveMode

ErrMessPicExit	IniFileDir	Version


ErrMessHandling Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessHandling: TPxRetrErrMessHandling;

Description

TPxRetrErrMessHandling = (remNoShow,remDialog,remException);

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling properties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessHandling Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessMax Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessMax: TCaption;

Description

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling proerties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessMax Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessMin Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessMin: TCaption;

Description

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling proerties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessMin Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicExit Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessPicExit: TCaption;

Description

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling proerties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessPicExit Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicInput Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessPicInput: TCaption;

Description

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling proerties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessPicInput Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessPicPaste Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessPicPaste: TCaption;

Description

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling proerties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessPicPaste Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


ErrMessRequired Property

Applies To

TPxValcheckRetriever

Declaration

property ErrMessRequired: TCaption;

Description

The ErrMess* properties of TPxValcheckRetriever are used to store defaults for the PxPicEdits and -Grids connected. If the Edit's/Grid's ErrMessHandling proerties are set to emRetriever, the controls will retrieve the error messages and the actual ErrMessHandling from TPxValcheckRetriever.

However, 'local' errormessages will not be overriden, allowing you to store any default messages with the Retriever and still have a custom errormessage with the controls itself.


ErrMessRequired Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


IniFileDir Property

Applies To

TPxValcheckRetriever

Declaration

property IniFileDir: TFileName;

Description

If a value is supplied here, the Retriever stores/searches for the inifile(s) in that directory. If
no value is supplied, the directory of the table to which the valcheck setting/retrieving applies
is used.


IniFileDir Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


IniFileExt Property

Applies To

TPxValcheckRetriever

Declaration

property IniFileExt: TFileExt;

Description

Used to supply a custom file extension for the valcheck inifile. Default extension is VCH.


IniFileExt Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


IniFileName Property

Applies To

TPxValcheckRetriever

Declaration

property IniFileName: TCaption;

Description

If supplied, the valchecks for all tables will be written to / retrieved from a single inifile. If not,
one file per table  will be used (name of the inifile will then be tablename+IniFileExt).

Storing valchecks in ini files lets you mimick the Paradox *.val files for any other breed of database. That way PicEdits can be used for any db that uses the BDE for data access.

You can change the extension of the ini file to be used so that end users will not recognize these files at first glance (see IniFileExt). You can also assign a certain directory where the file will be created/looked for which is useful especially with SQL databases (see IniFileDir).

For setting checks at design-time  you can use the PXCUST app included with PicEdits.


IniFileName Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


RetrieveMode Property

Applies To

TPxValcheckRetriever

Declaration

property RetrieveMode: TPxRetrieveMode;

see also

TPxRetrieveMode

OnAfterRetrieve

Description

This property determines which valcheck is to be retrieved from which set of valchecks.

PxValOnly and CustomOnly will both ignore the other set of valchecks.

EventOnly will ignore any given sets of valchecks and will just trigger the OnBeforeRetrieve and
OnAfterRetrieve events. You will have to supply your valchecks from within those events then
(you can load them from an inifile of your own, read them from a stream or a ressource,
hardcode them and so on...)

With PxValFirst/CustomFirst only checks which are not included with the 'first' set of valchecks are supplied from the second one.

For example: if RetrieveMode is PxValFirst and the Paradox val file includes settings for Min and Max only, a Picture setting from the custom vch file will be added to the checks retrieved. If there is a Picture setting with the val file however, the custom setting will be ignored. So in order to overwrite val file settings with custom settings you will have to switch RetrieveMode to CustomFirst. The Required value, however, is always taken from the first set of checks (as there is no null value defined for booleans - you can drop me a mail if you'd prefer a different proceeding here).

You can always use the OnAfterRetrieve event to override any setting from the val file.


RetrieveMode Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Version Property

Applies To

TPxValcheckRetriever

Declaration

property Version: string;

Description

Version


Version Example

- ENTER DESCRIPTION HERE -

procedure TForm1.Button1Click(Sender: TObject);


Methods

GetFieldValchecks	SetCustomValchecks


GetFieldValchecks Method

Applies To

TPxValcheckRetriever

Declaration

function GetFieldValchecks(var AFieldVchk: TPxFieldVchk;ADataSet: TDBDataSet;AFieldName: TComponentName): TPxRetrieveResult;

Description

GetFieldValchecks allows you to retrieve a fields valchecks at runtime.

The valchecks are written to a TPxFieldVchk structure:

  PPxFieldVchk = ^TPxFieldVchk;
  TPxFieldVchk = record
    VchkIniName: TFileName;     file holding custom checks - supplied even if there are none.
                                               You can use this value to evaluate tablename and directory
    FieldNum: integer;                phys. field number as with TTable.Fields[i].FieldNo
    HasValchecks: boolean;
    HasMin: wordbool;
    HasMax: wordbool;
    HasDef: wordbool;
    Required: boolean;
    MinValue: TCaption;
    MaxValue: TCaption;
    DefValue: TCaption;
    Picture: TCaption;
    LookUpTable: TCaption;
    LookUpType: LkUpType;
  end;

The result value of this function is defined as

TPxRetrieveResult = (vresOk,vresHasNone,vresInvalidHnd,
                               vresFieldNotFound,vresBDEError,vresError);


SetCustomValchecks Method

Applies To

TPxValcheckRetriever

Declaration

procedure SetCustomValchecks(ATable: TTable;AFieldName: TComponentName;const AReqVal: boolean;const AMinVal, AMaxVal,ADefVal, APicVal: TCaption);

Description

Use this method to write custom valchecks to a file either associated with a table or a
database (see the IniFile properties of TPxValcheckRetriever for details on this)

Example:

SetCustomValchecks(Table1, 'Quantity', True, '1', '100', '', '');

will place a minimum check of 1 and a maximum of 100 to field 'Quantity' of the table
connected to Table1. Required is also set to True. The valchecks will be written to a
TABLENAME.VCH ini file in the table's directory. Thus the valchecks will be permanent
and will apply to any PicEdit component that is connected to a PxValcheckRetriever with
the appropriate RetrieveMode set.

For setting checks at design-time  you can use the PXCUST app included with PicEdits.


Events

OnAfterRetrieve	OnBeforeRetrieve


OnAfterRetrieve Event

Applies To

TPxValcheckRetriever

Declaration

property OnAfterRetrieve: TPxAfterRetrieveEvent;

see also

TPxAfterRetrieveEvent

Description

OnAfterRetrieve presents you with the settings that have been retrieved for the given field and dataset, providing the opportunity to change each single value.

This is useful for overriding valcheck values at runtime. Also, if you don't want to use *.val files or don't want to store your checks in custom ini files this event of TPxValcheckRetriever
provides a central place for assigning checks to all all your DataSets and Fields. Have a look at the PXDEMO sample for an example.

NOTE If you have a Paradox *.val file set up and override min or max values at runtime be aware that you cannot 'fool' the BDE: any value < min or > max will cause the VCL to raise an exception when the user tries to post the record.


OnBeforeRetrieve Event

Applies To

TPxValcheckRetriever

Declaration

property OnBeforeRetrieve: TPxBeforeRetrieveEvent;

see also

TPxBeforeRetrieveEvent

Description

OnBeforeRetrieve provides the opportunity to redirect the valcheck request to another
dataset and/or another field and to temporarily change the retrieve mode. This is extremely
useful if you want to edit a live query which will have neither a val file nor custom settings (as
it is being created at runtime...). Simply evaluate the dataset and field in OnBeforeRetrieve
and if it's a query or a temporary table you supply a table with the original val settings for that
dataset.

Example: supposed you have a live result Query1 that points to the same table as your
Table1 does. There are DBPxPicEdits/Grids connected to that Query1. In the BeforeRetrieve
event place the following simple code and the valchecks will be retrieved from the table
connected to Table1 instead. Only drawback is that you will have to provide an open TTable
pointing to the source of your valchecks - but the benefits should make up for this...:

procedure TForm1.PxValcheckRetriever1BeforeRetrieve(Sender: TObject;
  var ADataset: TDBDataset; var AFieldName: TComponentName;
  var RetrieveMode: TPxRetrieveMode);
begin
  if ADataset = Query1 then
    ADataset := Table1;
end;

Of course you can also change the fieldname and the RetrieveMode from within this event.
The change of RetrieveMode is not permanent, it is only valid for this one call. For a
permanent change use the RetrieveMode property.


EPxPicInvalidGridOperation Type

Unit

PicEdits

Declaration

EPxPicInvalidGridOperation = class(Exception);

Description

- ENTER DESCRIPTION HERE -


EPxValidateError Type

Unit

PxConsts

Declaration

EPxValidateError = class(Exception);

see also

ErrMessHandling

Description

Custom Exception class that is used to indicate errors with the PicEdit components.


PPxFieldVchk Type

Unit

PxConsts

Declaration

PPxFieldVchk = ^TPxFieldVchk;

Description

Pointer type of TPxFieldVchk:

   structure holding field valchecks
  PPxFieldVchk = ^TPxFieldVchk;
  TPxFieldVchk = record
    VchkIniName: TFileName;
    FieldNum: integer;
    ErrorMessage: TCaption;
    HasValchecks: boolean;
    HasMin: wordbool;
    HasMax: wordbool;
    HasDef: wordbool;
    Required: boolean;
    MinValue: TCaption;
    MaxValue: TCaption;
    DefValue: TCaption;
    Picture: TCaption;
    LookUpTable: TCaption;
    LookUpType: LkUpType;
  end;


TPxAfterRetrieveEvent Type

Unit

PxConsts

Declaration

TPxAfterRetrieveEvent
= procedure(Sender: TObject;
            ADataset: TDBDataset;
            AFieldName: TComponentName;
            ARetrieveMode: TPxRetrieveMode;
            var AReqVal: boolean;
            var AMinVal, AMaxVal, ADefVal, APicVal: TCaption)
            of object;

see also

TPxValcheckRetriever

Description

This type is used with the OnAfterRetrieveEvent of TPxValcheckRetriever.


TPxBeforeRetrieveEvent Type

Unit

PicEdits

Declaration

TPxBeforeRetrieveEvent = procedure(Sender: TObject;
                                      var ADataset: TDBDataset;
                                      var AFieldName: TComponentName;
                                      var ARetrieveMode: TPxRetrieveMode)
                                      of object;

see also

TPxValcheckRetriever

Description

This type is used with the OnBeforeRetrieveEvent of TPxValCheckRetriever.


TPxDefaultMode Type

Unit

PxConsts

Declaration

TPxDefaultMode = set of TPxDefaultType;

Description

(not used yet)


TPxErrMessHandling Type

Unit

PicEdits

Declaration

TPxErrMessHandling = (emNoShow,emDialog,emException,emRetriever);

Description

- ENTER DESCRIPTION HERE -


TPxFailType Type

Unit

PxConsts

Declaration

TPxFailType = (ftNone, ftOtherFail, ftVchkTypeFail, ftMinFail, ftMaxFail, ftReqFail, ftPicExFail, tPicInFail, ftPicPasteFail, ftPicSyntaxFail, ftRetrieveError, ftSetupError, ftDefaultFail);

see also

OnValidate

OnFailValidate

Description

This type is used in OnValidate and OnFailValidate events.

ftNone:	No error...

ftOtherFail:	The unknown error, set FailType to this value to when you want to create a
custom error in OnAfterValidate or OnBeforeValidate.

ftReqFail:	Value is empty but required.

ftMinFail:	Value fails the minimum validation.

ftMaxFail:	Value fails the maximum validation.

ftVchkTypeFail:	An error ocurred while converting the value for min/max validation (both
controls) or due to the VchkType setting (PxPicEdit only).

ftPicInFail:	A char which is not allowed with the current picture has been entered.

ftPicExFail:	A request to leave the field or to post the value failed because the value is
not allowed with the current picture (meaning that it is incomplete unless
ftPicInFail errors have been canceled).

ftPicPasteFail:	A value which is not allowed with the current picture has been pasted.

ftPicSyntaxFail:	This is a special kind of error. You won't get any errormessage and you
won't be able to cancel the message or the error itself. ftPicSyntaxFail
means that the syntax of the picture string (or the picture parser, if there's
a bug...) failed. The current picture is set to none after this error, so it only
occurs once (until the next failing picture is supplied, of course).

ftRetrieveError: 	(DBPxPicEdit only) An error has occurred while trying to retrieve the fields
valchecks.

ftSetupError: 	An error has occurred while trying to set up the either TPxPicValidator or
TPxMinMaxValidator, which are responsible for the internal validation
process. (not fully implemented yet)


TPxFailValidateEvent Type

Unit

PicEdits

Declaration

TPxFailValidateEvent
= procedure(Sender: TObject;
            ValText, ErrorMessage: string;
            FailType: TPxFailType;
            var CancelMessage: boolean)
            var CancelError: boolean) of object;

see also

TPxFailType

Description

This event is triggered each time a validation fails. It does not cover the exceptions raised by
the BDE when you try to post an illegal value. You can use this event to roll your own error
handling, error dialogs, to direct the error messages to a status panel and so on...

Use FailType to evaluate the kind of failure:

ftNone: 	No error.

ftOtherFail:	The unknown error, set FailType to this value to when you want to create a
custom error in OnAfterValidate or OnBeforeValidate.

ftReqFail:	Value is empty but required.

ftMinFail:	Value fails the minimum validation.

ftMaxFail:	Value fails the maximum validation.

ftVchkTypeFail:	An error ocurred while converting the value for min/max validation (both
controls) or due to the VchkType setting (PxPicEdit only).

ftPicInFail:	A char which is not allowed with the current picture has been entered.

ftPicExFail:	A request to leave the field or to post the value failed because the value is
not allowed with the current picture (meaning that it is incomplete unless
ftPicInFail errors have been canceled).

ftPicPasteFail:	A value which is not allowed with the current picture has been pasted.

ftPicSyntaxFail:	This is a special kind of error. You won't get any errormessage and you
won't be able to cancel the message or the error itself. ftPicSyntaxFail
means that the syntax of the picture string (or the picture parser, if there's
a bug...) failed. The current picture is set to none after this error, so it only
occurs once (until the next failing picture is supplied, of course).

ftRetrieveError: 	(DBPxPicEdit only) An error has occurred while trying to retrieve the fields
valchecks.

ftSetupError: 	An error has occurred while trying to set up the either TPxPicValidator or
TPxMinMaxValidator, which are responsible for the internal validation
process. (not fully implemented yet)

ValText is used to evaluate the text which caused the failure.

ErrorMessage is the string that would be displayed by the default error dialog and can be
used to build your own dialogs.

Set CancelMessage := True to supress the beep and the display of the error message.

Set CancelError := True  it to to override the error i.e. to accept a value or to enable leaving
the field (the BDE will raise an exception, however, when you finally post min, max or
required failures! Only picture validation can be fooled completely.).

see also

OnValidate

OnFailValidate

Description

This type is used in OnValidate and OnFailValidate events.

ftNone:	No error...

ftOtherFail:	The unknown error, set FailType to this value to when you want to create a
custom error in OnAfterValidate or OnBeforeValidate.

ftReqFail:	Value is empty but required.

ftMinFail:	Value fails the minimum validation.

ftMaxFail:	Value fails the maximum validation.

ftVchkTypeFail:	An error ocurred while converting the value for min/max validation (both
controls) or due to the VchkType setting (PxPicEdit only).

ftPicInFail:	A char which is not allowed with the current picture has been entered.

ftPicExFail:	A request to leave the field or to post the value failed because the value is
not allowed with the current picture (meaning that it is incomplete unless
ftPicInFail errors have been canceled).

ftPicPasteFail:	A value which is not allowed with the current picture has been pasted.

ftPicSyntaxFail:	This is a special kind of error. You won't get any errormessage and you
won't be able to cancel the message or the error itself. ftPicSyntaxFail
means that the syntax of the picture string (or the picture parser, if there's
a bug...) failed. The current picture is set to none after this error, so it only
occurs once (until the next failing picture is supplied, of course).

ftRetrieveError: 	(DBPxPicEdit only) An error has occurred while trying to retrieve the fields
valchecks.

ftSetupError: 	An error has occurred while trying to set up the either TPxPicValidator or
TPxMinMaxValidator, which are responsible for the internal validation
process. (not fully implemented yet)


TPxFieldVchk Type

Unit

PxConsts

see also

GetFieldValchecks

Declaration

TPxFieldVchk = record

Description

This structure is used with method TPxValcheckRetriever.GetFieldValchecks

   structure holding field valchecks
  PPxFieldVchk = ^TPxFieldVchk;
  TPxFieldVchk = record
    VchkIniName: TFileName;
    FieldNum: integer;
    ErrorMessage: TCaption;
    HasValchecks: boolean;
    HasMin: wordbool;
    HasMax: wordbool;
    HasDef: wordbool;
    Required: boolean;
    MinValue: TCaption;
    MaxValue: TCaption;
    DefValue: TCaption;
    Picture: TCaption;
    LookUpTable: TCaption;
    LookUpType: LkUpType;
  end;


TPxRetrErrMessHandling Type

Unit

PxConsts

see also

ErrMessHandling

Declaration

TPxRetrErrMessHandling = (remNoShow,remDialog,remException);

Description

This type is used to control the DBPxPicEdit and -Grid error handling via
TPxValcheckRetriever.


TPxRetrieveMode Type

Unit

PxConsts

Declaration

TPxRetrieveMode = (retrPxValOnly, retrPxValFirst,
 retrCustomOnly, retrCustomFirst,
 retrEventOnly);

Description

This property determines which valcheck is to be retrieved from which set of valchecks.

PxValOnly and CustomOnly will both ignore the other set of valchecks.

EventOnly will ignore any given sets of valchecks and will just trigger the OnBeforeRetrieve and
OnAfterRetrieve events.

With PxValFirst/CustomFirst only checks which are not included with the 'first' set of valchecks
are supplied from the second one.


TPxRetrieveResult Type

Unit

PicEdits

Declaration

TPxRetrieveResult = (vresOk,vresHasNone,vresInvalidHnd,vresFieldNotFound,vresBDEError,vresError);

Description

- ENTER DESCRIPTION HERE -


TPxValidateEvent Type

See Also

Unit

PicEdits

Declaration

TPxValidateEvent = procedure(Sender: TObject;
                     var ValText, ErrorMessage: TCaption;
                     var FailType: TPxFailType
                     var ValType: TPxValType) of object;

Description

ValText is used to evaluate the text that is being validated and can be changed from within
OnValidate. Make sure that FailType is set to ftNone to override any failures the original text
may have caused.

FailType is the validation result. You can change it's value it to override errors or to trigger errors.

TPxFailType = (ftNone, ftOtherFail, ftVchkTypeFail,
                       ftMinFail, ftMaxFail, ftReqFail,
                       ftPicExFail, ftPicInFail,ftPicPasteFail, ftPicSyntaxFail,
                       ftRetrieveError,ftSetupError,
                       ftDefaultFail);

ftNone	no error
ftOtherFail	unknown error
ftVchkTypeFail  	value doesn't match the VchkType setting
ftMinFail	value doesn't match the min setting
ftMaxFail	value doesn't match the max setting
ftReqFail	value required failure
ftPicExFail	value doesn't fit picture setting on exit
ftPicInFail	value doesn't fit picture setting on input
ftPicPasteFail	value doesn't fit picture setting on paste
ftPicSyntaxFail	picture setting failed syntax test
ftRetrieveError	error retrieving valcheck values
ftSetupError	error setting up valcheck tests
ftDefaultFail	error supplying default value

ValType indicates what kind of validation is taking place.

TPxValType = (vaRequestInput, vaRequestExit, vaRequestPost, vaRequestUser);

vaRequestInput	a key has been pressed or a text pasted. Applies to pictures only.
vaRequestExit	an attempt to leave the control.
vaRequestPost	an attempt to post the current value. Applies to DBPxPicEdit only.
vaRequestUser              the Validate or PicValidate method has been called.


TPxValType Type

See Also

Unit

PicEdits

Declaration

TPxValType = (vaNone, vaRequestInput, vaRequestExit, vaRequestPost, vaRequestUser);

Description

This type is used in OnValidate and OnFailValidate events.

vaRequestInput	A key has been pressed or a text pasted. Applies to pictures only.
vaRequestExit	An attempt to leave the control.
vaRequestPost	An attempt to post the current value. Applies to DBPxPicEdit only.
vaRequestUser              The Validate or PicValidate method has been called.


TPxVchkSubType Type

Unit

PxConsts

Declaration

TPxVchkSubType = (vs_None, vsdShortDate, vsdDDMMYY, vsdDDMMYYYY,
vsdDDMMMYY, vsdDDMMMYYYY, vstLongTime,
vstShortTime, vstHHMM, vstHHMMSS);

Description

(not used yet)


TPxVchkType Type

Unit

PxConsts

Declaration

TPxVchkType = vchkNone, vchkString, vchkNumeric, vchkCurrency,
  vchkDate, vchkTime, vchkDateTime);

Description

This type is used with TPxPicEdit and determines

a) the datatype of the value accepted by this field. If you have your VchkType set to
vchkDate for example, only valid dates will be accepted regardless of whether any min or
max values are validated.

b) the way the MinMaxValidator works. When you change this setting, Min-, Max- and
DefaultValue is checked for compatability with the new setting. In design mode you will get
an error message for every imcompatible value and the value will be cleared. During runtime,
all values will be cleared when you change this setting. So if you want to change this
property at runtime, be sure to change this first and then supply new values.

There's one exception to this rule: if you change to vchkNone, no values will be cleared (and
no Min/Max validation will be performed regardless of Min- or MaxValues). If you change
back from vchkNone to any other setting, PxPicEdit will try to keep your values. However, if
either Min, Max or Default fails, this value will be cleared.

In design mode, on setting VchkType to vchkDate or vchkTime there will be a picture
suggestion, which should refect your ShortDateFormat resp. LongTimeFormat settings.

With vchkNumeric, if you want fixed decimals (or no decimals, i.e. integers) you can easily do
this by setting up pictures. Example: #*#[,##] will allow 1 to any number of digits, followed
by either none or  2 decimals. #[#],### will allow 1 or two digits and enforce 3 decimals.
'#*#' is the integer setting.


Registration

By Mail	Credit Card	Compuserve

At the moment there are two ways of getting registered. One is with CompuServe's SWREG, the other is by mail (International Postal Money Orders). If you'd prefer a cheque or bank remittance please drop me a mail first.

Sorry, I don't support credit card enterprises....

Registration Benefits

What you will get for your money:

full working version for royalty free use in your apps,
free upgrades for a year,
fast support via e-mail,
both 16 and 32bit versions.

Source code registration

As the code for PicEdits includes portions written by Borland (I had to get at quite a few private properties) only owners of the VCL source code are allowed to register PicEdits with source code. By registering with source you agree with this and at the same time assure that you own the VCL sources. The VCL sources can be obtained by buying it separately (D1) or by upgrading your D2 Standard Edition to either Developer or C/S. Contact your Borland vendor or Borland Customer Service for details.

Questions & Comments

Please adress all comments, questions and suggestions to

Reinhard Kalinke
Jahnstr. 45
D-29549 Bad Bevensen
Germany
e-Mail: 100417.3504 @compuserve.com


Registration By Mail
To Register By Mail

Select "Print Topic" from the "File" menu to print this form.

PicEdits suite

PicEdits suite w/o code. Price is $40.
PicEdits suite with code. Price is $75.

German residents please add 15% sales tax.

Please register my copy of PicEdits ,
I am sending a check or money order for $___________

Name:________________________________________________

Company:_____________________________________________

Address1:____________________________________________

Address2:____________________________________________

City:________________________________________________

State:_______________________________________________

Zip:_________________________________________________

Country:_____________________________________________

Phone:_______________________________________optional

e-mail:______________________________________________

Send completed form with payment to:

Reinhard Kalinke
Jahnstr. 45
D-29549 Bad Bevensen
Germany

Don't forget to include your e-mail adress!


Registration By Credit Card
To Register With Credit Card

Sorry, credit cards are not supported. Please register via mail or SWREG


Registration Via Compuserve
To Register Via Compuserve

If you have a Compuserve account, this is the fastest way to register

PicEdits suite

GO SWREG and select one of the numbers below, the registration fee
will be billed to your Compuserve account.

9768 for the PicEdits suite w/o code. Price is $40.
9769 for the PicEdits suite with code. Price is $75.


Installation

PicEdits

GETTING STARTED
---------------
- Unzip 'PICEDITS.ZIP' to a temporary directory.
  Use Option -d to preserve subdirectories.

Contents of the ZIP archive:

- root directory:
  the files you need to install 16bit PicEdits to your
  COMPLIB plus two readme files: PX_WHATS.NEW and
  PX_INST.TXT (which you are currently reading...)

- subdir PX_D2:
  the files you need to install 32bit PicEdits for
  Delphi2 to the component library.

- subdir PXHELP:
  the help files you need to integrate PicEdits help
  with the Delphi help system.

- subdir PXCUST:
  a simple editor for custom valchecks (to learn about
  custom valchecks, have a look at the TPxValcheckRetriever
  section in PICEDITS.HLP)

- subdir PXDEMO:
  a simple demo on how to use the TPxValcheckRetriever
  component (again you should have a look at the help file first
  and then on the comments in PXDEMO1.PAS for details).

- subdir PXTABLE:
  the *.DB and *.DBF files you need to run PXDEMO. Please copy
  these tables to your DBDEMOS alias.

Sorry, I did not find the time yet to include a decent demo on
PicEdits in general. I will add this as soon as I can find the time.
In the meantime please browse the help file to get an idea of how
PicEdits work.

If you have any questions concerning the use of PicEdits don't
hesitate to give me a mail.

INSTALLING THE HELP FILES
-------------------------
- If you are currently running Delphi, exit it now.  You cannot
  install the help files while Delphi is running.

- Move the file 'PICEDITS.HLP' to the Delphi 'Bin' directory
  ('C:' by default).

- Move the file 'PICEDITS.KWF' to the Delphi 'Help' directory
  ('C:' by default).

- Run the program 'HelpInst' from the 'Help' directory
  mentioned above.

- From HelpInst, load the file 'Delphi.hdx' which should be in
  the 'Bin' directory.

- From HelpInst, Add the file 'PICEDITS.KWF' to the list of indexes.

- From HelpInst, Save the new index file and exit the program.

- PicEdits's Help file will now be merged with Delphi's.

INSTALLING THE COMPONENTS
------------------------------
- If you don't already have a directory for add-on components,
  create one at this time.  It is always a good idea to install
  new components in a directory separate from those included
  with the language (e.g. ':').

- Move all *.DCU, *.DCR and and *.REG files plus the file
  PXPICREG.PAS (PXREG2.PAS for the 32bit version) from the
  temporary directory to your directory for add-on components
  (e.g. 'C:').

- Run Delphi and select 'Install Components' from the
  'Options' menu (for Delphi 2 it's 'Install' from the
  'Component' menu).

- If it's not already there, add the directory you store new
  components in, to the Search Path.

- Click on the 'Add' button and then the 'Browse' button to
  navigate to the add-on components directory mentioned above
  (e.g. 'C:').

- Select the file PICREG.PAS from the files list.

- Click on the 'OK' button to rebuild the VCL.

- The components will appear in the 'PicEdits' tab.

Browse PX_WHATS.NEW and the PICEDITS.HLP file for details
on how to use PicEdits and on the additional files.

If in doubt please refer to your Delphi manual on how to add components to the VCL.

NOTE: For all controls it is required that the files PXVALCHK.DCU and PXCONSTS.DCU are in the
lib's path (in the same directory as the other PX*.DCU files), PXVALRTR.DCU is a (recommended) option with DBPxPicEdit and DBPxPicGrid only.

PXVALCHK.DCU does not install as a component, installation of PXVALRTR.DCU as a
component is optional (see above).

The components will by default install to a page 'PicEdits' in your complib. Choose
'Configure' from the palette's popup menu or walk Delphi's 'Options' menu to move them to
another page of your choice.

Copy PICEDITS.HLP to the directory holding your help files (usually DELPHI) and PICEDITS.KWF to the directory holding the keyword files (usually DELPHI). Launch HELPINST.EXE to recompile the DELPHI.HDX MultiHelp file (refer to your Delphi manual for details).


Date_Time
Date & Time issues

PicEdits

PicEdits support dateformat dd-Mon-yy(yy). If your app's sysvar ShortDateFormat (see
OLH) is set to let's say 'dd-mmm-yy' (remember to set DateSeparator according to your
ShortDateFormat, too), then you can display, edit and validate this dateformat with
DBPxPicEdit and PxPicEdit will accept and validate it correctly. One place for setting this var
is the *.dpr file, first line of executed code, add SysUtils to the uses-clause. If you do it in the
Create event of your (main)form, you will have to set the DisplayFormat of your date fields to
that value, too, in order to have a correct display at startup.

If you want to use a HH:MM display with a time field, you will have to set LongTimeFormat for
your app to 'hh:nn'. Everything else is the same as with dateformat.

On setting the VchkType property, PxPicEdit will suggest a picture that will reflect your
general (i.e. WIN.INI) settings. The suggested pictures are not at all perfect, you can still
enter invalid dates like 02/30/96 for example, but you won't get away with this when you try to
leave the field. The suggestions are - well, suggestions.

Please give me a note if you'd like to see dedicated date and time PicEdits which could
provide more date and time specific features.


Tips for Validation on a form
Tips for handling validation on a form

PicEdits

Here are a few simple tricks for handling validation with the PicEdit components. It's only to
give you an idea, there sure is place for some refinement... one more time: any suggestions
welcome.

Keeping the BDE from raising valcheck exceptions

To ensure that all DBPxPicEdits connected to a DataSource have done their validations
before posting a record, add the following procedure to your form's unit:

procedure TForm1.DataSourcesUpdateData(Sender: TObject);
var i: integer;
begin
  with Form1 do
    for i := 0 to ComponentCount-1 do
      if (Components[i] is TDBPxPicEdit)
      and (TDataSource(Sender) = TDBPxPicEdit(Components[i]).DataSource) then
        if not TDBPxPicEdit(Components[i]).Validate then
          SysUtils.Abort;
end;

Set your DataSources' UpdateData property to this procedure and TDBPxPicEdit will
'prevalidate all fields valchecks before the record is actually given to the BDE for posting. If a
valcheck fails, the corresponding error proc is called and (unless overriden in
OnFailValidate) the failing TDBPxPicEdit will get the focus to have the user supply a valid
entry.

Implementing a Cancel button with PicEdit components

If you want the user to be able to cancel a dialog (or to call some routines helping him with
the value) despite invalid entries of any PicEdits, you might want to use the following
approach:

...
var
  Form1: TForm1;
  GoBackTo: TComponent;
...
implementation

$R *.DFM
...
procedure TForm1.GenericFailValidate(Sender: TObject;
  ErrorMessage: String; FailType: TFailType; var CancelMessage,
  CancelError: Boolean);
begin
This proc has been created by doubleclicking the objectinspector on any
 PicEdit's OnFail, the name has the be changed to 'GenericFail...', and
 it has then been assigned to all PicEdits
  if (ActiveControl = CancelButton) then
  begin
    GoBackTo := (Sender as TComponent);
    CancelError := True;
    you can assign ErrorMessage to a var, too, if you want to issue
     an info in CancelButtonExit
  end;
end;

procedure TForm1.CancelButtonExit(Sender: TObject);
begin

  if the user didn't quit and tries to leave the cancelbutton,
   put him back to where the error is...
  The reason to do this here is to enable the user to tab to
  the cancelbutton from a PicEdit, but hinder him from overtabbing
  it if he didn't quit. If you don't want to allow tabbing to Cancel,
  you can place this inside the CancelButtonClick proc

  if GoBackTo <> nil then
  begin
    (GoBackTo as TPxPicEdit).SetFocus; to only set focus
    (GoBackTo as TPxPicEdit).Validate; raises last error again, too
    GoBackTo := nil;
    place any additional user info here
  end;
end;

procedure TForm1.CancelButtonClick(Sender: TObject);
begin
  if (MessageDlg('You really want to cancel?',
                mtConfirmation,[mbYes,mbNo],0) = mrYes) then
    Form1.Close;
end;
...


Tips on errors
Tips on errors with TDBPxPicEdit

PicEdits

When you get errors like 'Could not retrieve valchecks' or seemingly unrelated errors like
'Could not create window', increase your Stack/Local Heap (Options/Project, 32k/16k is the
recommended minimum for database apps). If you haven't already done so, try using a
separate PxValRtr.

If you have difficulties getting a certain picture string to work as expected, a) make
(excessive) use of group brackets: , and b) please send me a note contaning this picture
with a description of it's misbehavin' so that I can try to fix it. I would like to hear about every
picture that doesn't behave like in the DBD or in Paradox itself.


Disclaimer

PicEdits

...and here's the inevitable:

DISCLAIMER

The author cannot and does not warrant that any functions contained in the software will
meet your requirements, or that its operations will be error free.  The entire risk as to the
software performance or quality, or both, is solely with the user and not the author.  You
assume responsibility for the selection of the component to achieve your intended results,
and for the installation, use, and results obtained from the software.

The author makes no warranty, either implied or expressed, including without limitation any
warranty with respect to this software documented here, its quality, performance, or fitness
for a particular purpose. In no event shall the author be liable to you for damages, whether
direct or indirect, incidental, special, or consequential arising out the use of or any defect
in the software,  even if the author has been advised of the possibility of such damages, or
for any claim by any other party.

All other warranties of any kind, either express or implied, including but not limited to the
implied warranties of merchantability and fitness for a particular purpose, are expressly
excluded.

Delphi and Paradox are trademarks of Borland International.


FixedColor property

Applies to

TDBPxPicGrid

See also

TitleColor

FixedCols

Declaration

FixedColor: TColor;

Description

Determines the background color of FixedCols, if there are any.

See also IndicatorColor, TitleColor and FixedCols.


IndicatorColor property

Applies to

TDBPxPicGrid

Declaration

IndicatorColor: TColor;

Description

Sets the color of the indicator. For instance you can use this to set the indicator's color to
red when a validation failed (from within the OnValidate event):

if FailType <> ftNone then
  IndicatorColor := clRed
else
  IndicatorColor := clBlack

Of course you can also use this, together with FixedColor, to create colorful apps
(don't lay it on too thick...<g>)